Skip to content

spec(FIX-1788): amendment 1 · worker named at session create; fold round two - #2818

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-1788-amend-1
Oct 6, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-1788-amend-1

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

The FIX-1788 spec merged in #2812 before its round-two review was folded. The merged text still says a session learns its worker from the first message, so every message an app sends would carry worker. You said the worker belongs to the session, and that a session's worker can't change. Its app example also used clients.actions(...), which is a private Shift Manager lab wrapper, not a framework API.

What this does

It records your gate answers and moves the worker to session create. It changes only specs/issues/FIX-1788/. Nothing is implemented.

  • The worker is named once, when the session is created (new D4). The server checks it right there: it must be the user's own worker or a standard one, and it must run on this flow. The link sits in a field only the server writes, and it never changes. A session without a worker is refused. That includes an action sent to a session id that doesn't exist yet. Messages never carry worker.
  • Where the check runs. It runs in an engine hook that the flow declares, before the session record is written, on every path that writes one: the create request, an action on a missing session id, and a transport's session resolver. This is the session-record form of the epic's D3 change 3, as #2813 records it.
  • The same mechanism holds what changes after create. Session-state fields that only flow code writes, and that a create refuses from a caller. A coordinator's delegates live there for FIX-1791.
  • What an app writes. Today's client, plus three new names and two helpers. The roster gives each worker's flow. createSessionClient().createSession takes a worker option and listSessions takes a worker filter. A bound createWorkforceClient({ userId, baseUrl }) (the session client's transport options) has two methods: ensureWorkerSession({ worker }) finds the user's session or creates one, and findWorkerSession only checks. After that, createClient({ flowKind }).sendAction(action, input, { sessionId }) works as it does today. The helpers take one criteria object, so FIX-1794 and FIX-1793 can add keys to it later.
  • Two calls at once make one session. ensureWorkerSession creates the session at an id derived from the user, the org and the criteria. When two calls race, the store's existing insert-if-absent write gives the second call a 409, and that call returns the first session. The create check refuses a derived id that belongs to someone else.
  • When a worker changes under its sessions. If an edit moves the worker to a different flow, its old sessions refuse new turns and name both flows. A fork is a new worker, and old sessions stay with the original. A fire works as before.
  • Your answers. Q1 is now D3, decided as copy, with following later edits possible later as an opt-in. D1 and D2 are recorded as signed.
  • Cleanup. Every clients.actions(...) example is removed. The examples use only the public @flow-state-dev/client exports (createSessionClient, createClient) and the two helpers. Prose no longer says "seat", "person" or "kind". The draft docs teach createWorkerHireBlocks({ workerFlows }), which matches FIX-1789's rename of kinds (#2814). writtenBy.workerId comes from the link.
  import { createClient } from "@flow-state-dev/client"
+ import { createWorkforceClient } from "@flow-state-dev/workforce"

- const researcher = createClient({ flowKind: "acme.~alice.researcher", userId })
- await researcher.sendAction("run", { message }, { sessionId })
+ const workforce = createWorkforceClient({ userId, baseUrl })
+ const session = await workforce.ensureWorkerSession({ worker: "researcher" })
+ const agent = createClient({ flowKind: session.flowKind, userId })
+ await agent.sendAction("run", { message }, { sessionId: session.id })

What's asked of you

Approve this amendment: is the worker named at session create, as you meant?

D4: where a session learns its worker. Chosen: at create, in a server-only field on the session record. Instead of: on the first turn, in server-owned session state. Decides it: what carries the worker. The session carries it once, so messages never name one. The cost: an engine check on every way a session is made. Locks in a create check, plus worker on create and list. Flips if an app must open a session before it knows its worker.

  • The fork. A session learns its worker when it is created, or from its first message.
  • In plain terms. An app calls ensureWorkerSession({ worker: "researcher" }) and then sends ordinary messages. A session can't exist without a worker, and its worker can't change. Talking to a different worker means a different session.
  • The trade-off. The engine needs a create-time check on every path that opens a session. Without it, the worker flow would set the link on the first turn. In return, no message shape carries the worker, and no unlinked session ever exists.
  • My recommendation: approve as written. This is your direction from the review, and the epic already records it.
  • What would change my mind. An app that must open a session before it knows which worker will run it, such as a triage chat that hands off later.
  • If wrong. Every way of opening a session must know its worker up front. Before implementation, going back is cheap: the first-turn design is in spec(FIX-1788): A worker is a private resource its owner holds, run by the shared flow it names #2812's history. After P1 merges, the create hook is a public engine option.

Implementation of FIX-1788 waits for this amendment to merge.

Parts worth reviewing closely

  • DECISIONS.md → D4, and PLAN.md → S1: one session-birth function that every path reaches, fsdev run included. It owns the purge, the create check and the insert-if-absent write, and it holds the delegates' server-written state.
  • BUSINESS-RULES.md → BR-10 to BR-19c. The session rules, rewritten for create time. BR-13a covers racing calls, BR-13b squatting, BR-18a delegates, BR-19b and BR-19c an edit and a fork.
  • PLAN.md → S1, S5, S5a and Pinned names. S1 now includes client and react, because useFlow passes worker through. Pinned app-facing names are only worker on create, worker on list, the roster's flow, findWorkerSession and ensureWorkerSession.
  • SPEC.md → the goal check. Leg b's signal is reworked. The caller-link control still fails: under it, the server accepts the create's caller state and reads the link from it.

Links: original review #2812 (decision threads on SPEC.md L67: 1, 2, 3, 4; fold checklist 6024339940; gate answers 6024643873) · epic amendment #2813 · FIX-1789 amendment #2814 · retained spec specs/issues/FIX-1788/ · FIX-1788 · epic FIX-1786 · this PR merges into main after your approval

How to review this

This is a direction amendment, not an implementation. The question is whether the approach is right. This round changed the approach in one place, where a session learns its worker, and the rest follows from that: the app API, the rules and the plan.

  • In scope: D4, the mechanism in S1 and S5, the helpers' semantics (S5a), and whether the rules for a worker changing under its sessions match your intent.
  • Out of scope: D1 to D3, which are signed or decided, and exact signatures. Only the pinned names are fixed.
Contract and verification
  • Scope: only specs/issues/FIX-1788/. Never pushed to spec/FIX-1788 or spec(FIX-1788): A worker is a private resource its owner holds, run by the shared flow it names #2812.
  • Spec checks (spec-figures.md → Verify): fences balanced; no risky mermaid labels; every SVG has ext=0, one theme block, one aria-label and ≤96 lines; every nav line is present; every decision card (D1 to D4) has its trade-off figure; no figure is missing; node scripts/validate-spec-folder.mjs passes.
  • Figures rendered in light and dark with headless Chromium and checked by eye: d4-link-at-create.svg (new), d3-fork-copies.svg (was open-fork.svg, now CHOSEN), d2-org-wide-hire.svg, what-changes.svg.
  • POC re-run: node specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs → PASS, 23 flows over 94 of 94 WORKER.md files. CONTROL=drop-one → exit 1. Only its README wording changed.
  • Client surface checked against packages/client/src/index.ts: createClient, createTypedClient and createSessionClient are exported, SessionDetail carries flowKind, and sendAction(action, input, { sessionId }) matches.
  • Word budgets: every document is still over its template budget (DECISIONS 1,887 against ~900, PLAN 2,892 against ~1,000). Decided, not asked is now cut to what PLAN doesn't hold.
  • Third commit (99430a6) folds Codex: a fifth birth path (the dispatched-child writer), a lookup and derived id that are aware of the worker's flow, and the bound createWorkforceClient.
  • Second commit (5226872) folds the review on this PR: the architect (6024892197), the second look (6024879316), the coherence note (6024896388) and Cursor (5434236373).

🤖 Generated with Claude Code

https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV


Generated by Claude Code

…und two

#2812 merged before its round-two review was folded. This amendment:
- Q1 decided as copy (now D3); D1 and D2 recorded as signed.
- D4: a session's worker is named once, at create, in a server-only field
  on the session record (epic D3 change 3, as #2813 records). The engine
  runs a flow-declared create check on every path that writes a new
  session record; actions never carry `worker`; no session without one.
- The same S1 mechanism holds server-written session state that changes
  after create (FIX-1791's delegates).
- App API: today's client plus `worker` on createSession/listSessions,
  the roster's `flow`, and Workforce's findWorkerSession /
  ensureWorkerSession (one criteria object; racing ensure calls make one
  session via a derived id and the create's insert-if-absent write).
- Worker edited to another flow, forked, fired: rules for its sessions.
- Purges the lab-only `clients.actions(...)` example; retires seat,
  person and kind in prose; aligns with FIX-1789's `workerFlows` and
  `writtenBy.workerId`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
@jhoffner jhoffner added the spec label Oct 6, 2026 — with Claude
@vercel

vercel Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 6, 2026 8:37pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 6, 2026 8:37pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 6, 2026 8:37pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-06T20:34:47.719292Z f186b8b PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1788

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec-only PR, read against main)

Direction (D4: worker named at create, server-only field) is sound and I'd keep it. The "first-turn link" alternative really does leak into every message shape. Findings are about how S1 is scoped and whether the spec's picture of the engine matches the code.

1. The spec's list of create paths is incomplete, and it points at the wrong seam (should fold)

PLAN.md S1 and "At implement time" name three paths: the create route, an action on a missing id, a transport resolver. In the code there are two creation implementations, plus a direct caller of the public helper:

  • handleCreateSession (engine/src/routes/session-routes.ts ~L370-405) builds the record and does purgeStaleResourceState + session.set(..., "absent") itself. Its comment says it deliberately bypasses ensureSessionRecord.
  • ensureSessionRecord (engine/src/context/ensure-session-record.ts) does the same purge + insert-if-absent for createExecutionContext and the webhook session-resolver.
  • packages/cli/src/commands/run.ts:340 calls ensureSessionRecord directly, and ensureSessionRecord is exported from engine/src/index.ts. So fsdev run (the repo's default verification path) and any host code are a fourth path the guardrail "every path that writes a new record runs the check" doesn't name. The spec also says nothing about how fsdev run names a worker for a worker flow, and V1 should cover it.

Architecture opportunity, in scope because S1 touches exactly this: the two implementations already differ (409 vs adopt on a lost race, which is why the route has its own copy). Rather than wiring the hook into each call site and relying on a grep ("grep for others before you start"), have P1 introduce one session-birth function that owns purge + insert-if-absent + the flow's create check, and make both handleCreateSession and ensureSessionRecord thin callers of it. The hook then has one home and a new path can't skip it (tenet 5: enforce by construction, not by a list). Keep the 409/adopt difference as the caller's choice over the result. That is a refactor the feature needs, not drive-by cleanup.

Related detail to pin in S1: ensureSessionRecord's build is a sync callback and runs on a miss only. The async check must run on the miss path only, never on every turn of an existing session. State that, and add a V1 case: existing session, no check call.

2. S1's second half (server-written session-state fields) has no consumer in this issue

S1 ships two mechanisms: the create field (needed now) and "server-written state fields the create refuses from a caller", whose only user is FIX-1791's delegates. P1 would land a generic engine/core mechanism with no test driver beyond a fixture coordinator (BR-18a / V4). CLAUDE.md's simplicity rule says no speculative abstraction. Suggest either (a) cutting it from P1 and letting FIX-1791 add it against a real consumer, or (b) keeping it with one sentence saying why it can't wait (e.g. the create-refusal rule must exist before any app can seed those fields). Without that sentence, an implementer will build both. My lean is (a), unless the epic's D3 change 3 requires it now.

3. Lost-race behaviour differs by path; the spec only describes one

S5a and the "Racing calls" bullet say the loser gets a 409 from the store's insert-if-absent write. That is true on the create route. On the action-implicit-create path ensureSessionRecord returns the winner's record instead of a 409. That is fine for ensureWorkerSession (it uses the create route), but the spec should say which path the 409 contract belongs to, so nobody tests it on the other one. Also: when a lost-race winner is adopted on the action path, its worker was set by the winner's create check. State that the loser's input is not re-checked against it, and that this is intended.

4. Derived-id squatting check (BR-13b) needs a recognizable id format

"The create check refuses a derived id that isn't the caller's" requires the check to recognise a derived id and recompute it. Storage keys are tenant-prefixed (resolveSessionStorageKey). Say in S5 that the derivation lives in one exported function used by both ensureWorkerSession and the check, so the two can't drift, and that it runs on the tenant-resolved key.

5. Size and duplication (previously raised, still true)

PR body admits DECISIONS is ~2,350 words against ~900 and PLAN ~2,515 against ~1,000. The "Decided, not asked" block in DECISIONS restates PLAN S1, S5, S5a, and the guardrails. The pseudocode in PLAN restates the same flow a fourth time. The "Notes from review" section in PLAN already carries Cursor's "parallel prose" and "one owner for the mapping" notes unfixed; this amendment added more of the same prose rather than less. Suggest this PR (it's already touching these files) cut "Decided, not asked" down to what PLAN doesn't hold (fork/library seam, upgrade-step-as-code, ids) and link to PLAN S1/S5a for the mechanism. Fewer copies means fewer places to drift when FIX-1791/1793/1794 change the criteria object.

6. Smaller notes

  • S5a findWorkerSession returns "the most recent matching session" while ensureWorkerSession creates at a derived id. A user with several sessions made via plain createSession gets a different one back than the derived one. Fine, but say ensure returns the most recent, not the derived one, so docs don't imply a single canonical session.
  • Recreating a deleted derived id relies on purgeStaleResourceState tombstone reclamation. Worth one V4 case (delete, then ensureWorkerSession again), since the link must come back fresh rather than inherited.
  • Pinned names list is good. workerId as a persisted field name: confirm P1's field is a generic engine key (the spec says the engine knows no worker) and that workerId is only the value Workforce stores in it. As written, the two reads blur.

Verdict

Approve direction. Fold #1 (name the fourth path and the single-birth-function seam; this is the one that decides whether "every path" is true), decide #2 (cut or justify), and tighten #3-#4. #5 is a quality nit but cheap to do in this same PR.


Generated by Claude Code

@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Architect: coherence with FIX-1791 (#2815), one key to name

This matches epic D3 Locks in (3) on main (#2813): the worker is set and checked at create, never on a turn, and delegates sit in server-written session state (BR-18a). #2815 has already been told to merge after this PR and to cite these names. There's no fork. One gap to close in this amendment, so the two specs open delegate sessions the same way:

  • FIX-1791 needs its own criteria key, and S5a doesn't reserve one. FIX-1791 S5 delivers each pick "in its conversation for this coordinator conversation". In other words, Alice's researcher gets one session per coordinator conversation, and that spec's goal fails if "a change in one conversation shows in another". Under S5a, ensureWorkerSession({ worker: "researcher" }) derives one id from user, org and criteria. With only worker, every coordinator conversation would land in the same delegate session.
  • Ask: in S5a, Pinned names and EVOLUTION, list FIX-1791 next to FIX-1794 (taskId) and FIX-1793 (workstreamId) as a later criteria key, for the coordinator conversation the delivery belongs to. Don't name or define the key here; FIX-1791 pins it. If you'd rather have FIX-1791 open delegate sessions with plain createSession({ worker }) and keep its own map, say that in S5a instead. Either works. Not saying is the gap.
  • The delivery path depends on this. This amendment refuses an action on a missing session id that has no worker. So FIX-1791's first delivery to a delegate has to create the session with the worker named, through the helper or createSession. It can't post to a fresh id and let the turn link it. One line in BR-18a or S5a saying so closes it from this side. I'll carry the matching line to spec(FIX-1791): a coordinator hands each post to delegates it manages, by a routing policy #2815's fold.

Nothing else crosses: #2814's createWorkerHireBlocks({ workerFlows }) rename and the clients.actions(...) purge agree with the merged FIX-1789 amendment and with the decision on #2815.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Coherence note: finding #2 crosses into #2815 (FIX-1791)

Before you fold finding #2 (cut or justify S1's server-written session-state fields), note that the open FIX-1791 spec #2815 already depends on this PR for that mechanism. Its How line says: "one coordinator flow keeps the delegates in session state that only the server writes ([FIX-1788])".

If this PR takes option (a) and cuts it, while #2815 stays as written, each spec points at the other for the mechanism and nobody builds it. Pick one owner and make both specs say the same thing:

Either is fine. What we must avoid is the two specs disagreeing about who builds it. Also, check that epic D3 change 3 (as amended in #2813) doesn't already settle this before you choose.

Findings #1, #3, #4 and #5 don't touch another in-flight stream, so no coherence concern there.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify / approach review (FIX-1788 amend 1)

This is a spec-only PR (~1.7k lines): retained FIX-1788 issue spec + FIX-1786 epic sync + one retained POC (poc/flow-inventory/). I did not find production-code complexity to trim here; the interesting question is whether the documented implementation plan is heavier than the problem requires.

Verdict on the approach

The core architectural bet looks right and is hard to simplify without trading away safety or migration:

  • Worker named at session create (D4) is cleaner than first-turn linking or per-message worker fields — fewer app call sites, aligns with “session owns the worker,” and matches Jake’s #2812 direction.
  • One flow copy per kind (D3 / S10) vs per-hire registration is the real simplification win at runtime; the spec correctly pays migration cost in P3/P4 rather than stranding hires mid-stack.
  • Thin Workforce on generic S1 create-check + worker/workerId on the client keeps the engine workforce-agnostic; that layering is appropriate even though it adds surfaces (S1 + S5 + S5a).

I do not think a materially simpler product design exists without reopening epic gates (org-scoped workers, caller-seeded links, or keeping per-hire flow copies).

Where complexity did grow (and what I’d do instead)

Area Smell Lighter path (spec hygiene, not re-architecture)
Procedural contract in two places DECISIONS.md §“Decided, not asked” largely restates PLAN.md Surfaces / Guardrails / Sketch Keep D1–D4 outcomes + fork/library seam in DECISIONS; link to Plan for S1–S16 and checks. You already recorded this in Plan §“Notes from review” — worth doing before implementers treat both as canonical.
S5 vs S6–S8 Three PLAN rows + per-turn load/grants/state for one “execution slice” Consider one deep module (resolveWorker / single interface) as noted in Plan notes from #2812; optionally one PLAN surface row with sub-bullets for config · keyed resources · grants (table-only cleanup).
Naming layers DOCS.md drafts createCheck/link/createWorkerHireBlocks while Plan pins worker / workerId Add the “shipped names” box Plan §Pinned names asks for at the top of DOCS.md (or align draft tables now). Reduces P4 doc churn.
V0 evidence WORKER.md totality is automated; hireWorkforce census is manual rg Optional sibling POC under poc/ (FIX-1503 / FIX-1748 census style) — not required for direction approval, but avoids asymmetric evidence.
Retained POC inventory.mjs re-implements frontmatter/flow rules Fine for throwaway evidence; implementation must reuse readDeclaredFlow, loader walks, and discoverWorkforceCode — don’t copy POC heuristics into product code.

Performance (at implement time, not this PR)

When built: watch listSessions({ worker }) without a store index (S5a) and per-turn worker load + name resolution (S6–S8). Spec is correct to require per-turn freshness; implementation should cache within a run where the rules allow.

Must-fix before merge

D4’s one-line tagline under the figure contradicts the chosen horn (still describes first-turn / message-shaped linking). The figure alt text and “Considered and dropped” table say the opposite — easy for a skim-reader to implement the wrong thing.

Minor nits (optional)

  • S10 still says “in whichever declaration shape the epic recorded” — epic Q1 is now list; tighten wording.
  • Stale parallel between BR “Proved by” and PLAN V-ids — pick one owner (also in Plan notes).

Summary: Directionally approve the design; request one spec correction (D4 tagline) and encourage folding the review-round simplifications you already captured in Plan §“Notes from review” so the retained set has a single procedural owner before implementation PRs land.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1788/DECISIONS.md Outdated

![D4: where a session learns its worker. At create, in a server-only field on the session record, chosen, beside on the first turn in server-owned state. Decides it: what carries the worker, the session once, so messages never name one. Price: an engine check on every way a session is made. Locks in a create check and worker on create and list; flips if an app must open a session before it knows its worker](figures/d4-link-at-create.svg)

It comes down to what carries the worker: on the first turn, every message shape carries it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must fix: This line still states the rejected D4 horn (“on the first turn, every message shape carries it”). The card above, the figure alt text (L101), and the “Considered and dropped” row for first-turn linking all describe create-time linking.

Suggest replacing with something aligned with the chosen outcome, e.g. “It comes down to what carries the worker: the session, once, at create — so messages never name one.”

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Fixed in 5226872. The tagline now states the chosen option: "It comes down to what carries the worker: the session, once, at create, so messages never name one."


Generated by Claude Code

Comment thread specs/issues/FIX-1788/PLAN.md Outdated
| S8 | `workforce` · grants per turn | A worker's document grants and reference wall narrow what its model reaches on each turn: tools and context. Replaces the per-copy narrowed resource map | BR-24 |
| S9 | `workforce` · hire, fork, fire | Writes to S3, through the existing hire blocks and tool; fork is new beside them. Each turn names the collection it wrote | BR-1 BR-2 BR-4 BR-7 BR-8 |
| S9 | `workforce` · hire, fork, fire | Writes to S3, through the hire blocks and tool; fork is new beside them and copies per D3. The hire blocks take `workerFlows` (FIX-1789) and, since they change here, take a worker name (the docs draft `createWorkerHireBlocks`; not pinned). Each turn names the collection it wrote | BR-1 BR-2 BR-4 BR-7 BR-8 BR-19c |
| S10 | `workforce` · registration | The hire registers one copy per flow, `agent` and every flow handed to it, with no per-worker copy and no pin. The `agent` flow becomes a singleton, in whichever declaration shape the epic recorded | BR-26 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After epic Q1 closure (list at FIX-1789 gate), this reads stale. Consider: “…registers on the installation’s workerFlows list (epic Q1).” — drops “whichever declaration shape” ambiguity.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Fixed in 5226872. S10 now reads: "The agent flow becomes a singleton and registers on the installation's workerFlows list (epic Q1)."


Generated by Claude Code

renamed here (S9).

## Notes from review

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 on acting on this note before implementation: S5 + S6 as one deep module (resolveWorker → { worker, resolved config } + link path) would cut cross-coupling without changing the four-PR stack. Worth a single explicit line under S5/S6 in the Surfaces table if you adopt it.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Adopted in 5226872. S5 now says S5 and S6 are built as one module with one interface (resolveWorker returns the worker plus its resolved configuration, beside the create check), on the same PR stack.


Generated by Claude Code

Comment thread specs/issues/FIX-1788/DOCS.md Outdated
pin (the session-state option, the upgrade command, `fork`) are reconciled with the shipped
code before publishing. Q1's answer sets one sentence, marked below.
([`user-docs.md`](../../../docs/contributing/user-docs.md)) and uses the new terms: worker,
worker flow, user. Pinned names are `PLAN.md`'s. Draft names, reconciled with the shipped code

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplification for P4: Plan already pins public names (worker, workerId, helpers). This paragraph mixes draft API names (createCheck, link, createWorkerHireBlocks) with pinned ones. A short shipped names box (or aligning the session-table draft to worker on create) would avoid implementers/docs re-litigating exports — matches Plan §“Notes from review”.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Added in 5226872: a Shipped names box at the top of DOCS.md. Pinned: worker on createSession, worker on listSessions, the roster's flow, findWorkerSession, ensureWorkerSession (plus FIX-1789's workerFlows). Drafts: createCheck and its link input, serverOwned, createWorkerHireBlocks, fork, useFlow's worker, fsdev run --worker, the upgrade command.


Generated by Claude Code

…791 key

- Architect (6024892197): reserve FIX-1791's coordinator-conversation
  criteria key beside FIX-1794's and FIX-1793's (S5a, pinned names,
  EVOLUTION); BR-18a/S5a: a delivery opens the delegate's session via
  ensureWorkerSession with the worker named.
- Second look (6024879316): S1 is one session-birth function owning
  purge, create check and insert-if-absent; handleCreateSession and
  ensureSessionRecord become thin callers; fsdev run is the fourth path
  (--worker, V1 case); check on the miss path only (V1 case); 409
  belongs to the create route, the action path adopts; one exported id
  derivation on the tenant-resolved key; ensure returns the most recent
  match; delete-then-ensure V4 case; workerId is the value in a generic
  engine key; "Decided, not asked" trimmed to what PLAN doesn't hold.
- Coherence (6024896388): server-written state stays here (epic D3
  Locks in (3)), FIX-1791's delegates (#2815) consume it.
- Cursor (5434236373): D4 tagline states the chosen option; S10 names
  the workerFlows list; DOCS shipped-names box; S5 and S6 as one module.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f186b8b588

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-1788/PLAN.md Outdated
| ID | Package · role | Change | Rules |
|---|---|---|---|
| S1 | `engine` + `core` · session state declaration, the session create route | A flow can declare session-state fields server-owned. The create route refuses caller state for them with 400, naming the field; only flow code writes them. Unset means today. FIX-1791 keeps delegates here too | BR-15 BR-16 |
| S1 | `engine` + `core` + `client` + `react` · server-owned session data, at create | One declaration, two parts. **A create field:** the flow declares a create check; every path that writes a new session record for it (the create route, the record an action writes for a missing session id, a transport's session resolver) calls it with the verified principal and the create's input before the insert-if-absent write. It refuses, or returns a value the engine stores on the record outside `state`; no route writes it afterwards. A path with no input is refused. **Server-written state:** session-state fields the create refuses from a caller (400, naming the field) and only flow code writes; FIX-1791's delegates live here. The list route filters on the create field. The client's `createSession` takes `worker` and `listSessions` a `worker` filter, mapped onto that field; `useFlow` passes `worker` to both. The engine knows no worker. Undeclared means today | BR-13 BR-14 BR-15 BR-16 BR-18a |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Route dispatched child creation through the create check

When a task dispatcher targets a worker flow, create-request-host.ts writes the derived child SessionRecord directly before the target task entry executes. This path is absent from S1's supposedly exhaustive list, so S5 cannot enforce the check from the task entry after the unlinked record already exists; dispatched worker sessions will either lack workerId or fail on their first turn. Carry the worker/create input through this direct writer, run the create check there, and cover it in V1/V4.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Fixed in 99430a6.

  • PLAN S1 lists the dispatched-child writer (engine/src/context/create-request-host.ts) as the fifth path and routes it through the one session-birth function. The worker is carried from the dispatching flow's code, so the child is born linked.
  • The guardrail now reads: every SessionRecord insert goes through the birth function. It is enforced by construction, and V1 includes a grep that finds no other session.set(…, "absent") writer.
  • V1 and V4 add a task dispatched to a worker flow.

Generated by Claude Code

Comment thread specs/issues/FIX-1788/PLAN.md Outdated
| S5 | `workforce` · the link, one module | The check (the session user's own worker or a standard one · names this flow · no link yet) and the server-owned write, atomic per session: two racing first turns link one worker. The door's per-session concurrency or a versioned write, your pick; no Layer 1 change. The door, the task entry and the mailbox wake all call it | BR-10–14 BR-13a BR-18 BR-19 BR-19a |
| S6 | `workforce` · per-turn configuration | Load the linked worker each turn; resolve tool, skill, package, capability and worker-folder names against what the installation registers; refuse a turn whose names don't resolve, or whose flow is now standard-only. Every read of a worker setting moves off `ctx.flow.config` to it | BR-20–22a |
| S5 | `workforce` · the link, one module | The create check every worker flow declares through S1: a worker is named; it is the principal's own (read at their scope) or a standard one; it names this flow; a derived worker-session id is the caller's. It returns `workerId`. The task entry and the mailbox wake open sessions through it, naming the worker from the dispatching flow's code. No turn sets or changes a link | BR-10–14 BR-13b BR-18 |
| S5a | `workforce` · `findWorkerSession`, `ensureWorkerSession` | One lookup path over `listSessions({ …, worker })`, taking one criteria object. FIX-1788 ships `worker`; leave the object open for FIX-1794's and FIX-1793's keys, and define neither. `find` returns the caller's most recent matching session, or none. `ensure` finds, or creates on the flow the worker's roster row names, at an id derived from the caller's user, org and criteria; a 409 from the create means a racing call won, so it reads that id and returns it (the store's own create guarantee: SQLite, Postgres, one filesystem store instance). Where the helpers get the caller and transport is yours | BR-13a BR-14a |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Change ensured-session identity when a worker changes flow

When BR-19b edits a worker to use another flow, this worker-only lookup can return the now-unusable old-flow session. Even if lookup is narrowed to the current flow, the specified derived ID still uses only (user, org, criteria), and FIX-1788's sole criterion is the unchanged worker ID; creating the replacement therefore collides with the old session, takes the 409 path, and returns that same refusing session. Include the resolved flow or worker incarnation in reuse and ID derivation, and verify BR-19b through ensureWorkerSession.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Fixed in 99430a6.

  • S5a: both helpers resolve the worker's current flow from the roster first. The lookup and the derived id include that resolved flow, not just the criteria.
  • After BR-19b's edit, ensureWorkerSession finds nothing on the new flow and creates a fresh session at a new id. The old sessions keep refusing.
  • BR-19b says so, and V4 drives BR-19b through ensureWorkerSession.

Generated by Claude Code

Comment thread specs/issues/FIX-1788/PLAN.md Outdated
| S5 | `workforce` · the link, one module | The check (the session user's own worker or a standard one · names this flow · no link yet) and the server-owned write, atomic per session: two racing first turns link one worker. The door's per-session concurrency or a versioned write, your pick; no Layer 1 change. The door, the task entry and the mailbox wake all call it | BR-10–14 BR-13a BR-18 BR-19 BR-19a |
| S6 | `workforce` · per-turn configuration | Load the linked worker each turn; resolve tool, skill, package, capability and worker-folder names against what the installation registers; refuse a turn whose names don't resolve, or whose flow is now standard-only. Every read of a worker setting moves off `ctx.flow.config` to it | BR-20–22a |
| S5 | `workforce` · the link, one module | The create check every worker flow declares through S1: a worker is named; it is the principal's own (read at their scope) or a standard one; it names this flow; a derived worker-session id is the caller's. It returns `workerId`. The task entry and the mailbox wake open sessions through it, naming the worker from the dispatching flow's code. No turn sets or changes a link | BR-10–14 BR-13b BR-18 |
| S5a | `workforce` · `findWorkerSession`, `ensureWorkerSession` | One lookup path over `listSessions({ …, worker })`, taking one criteria object. FIX-1788 ships `worker`; leave the object open for FIX-1794's and FIX-1793's keys, and define neither. `find` returns the caller's most recent matching session, or none. `ensure` finds, or creates on the flow the worker's roster row names, at an id derived from the caller's user, org and criteria; a 409 from the create means a racing call won, so it reads that id and returns it (the store's own create guarantee: SQLite, Postgres, one filesystem store instance). Where the helpers get the caller and transport is yours | BR-13a BR-14a |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Specify identity and transport for the session helpers

In browser or Node clients using a non-default base URL or the framework's default identity resolver, findWorkerSession({ worker }) and ensureWorkerSession({ worker }) have no client transport, userId, or roster context from which to discover the flow and create/list sessions. The existing session client requires a constructed transport and non-empty flowKind/userId, so leaving where these values come from to the implementer makes the pinned context-free API impossible without inventing ambient state or a new endpoint. Pin a bound-client/factory or explicit options contract and update the examples accordingly.

AGENTS.md reference: AGENTS.md:L78-L78

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Fixed in 99430a6.

  • The helpers are methods on a bound client: createWorkforceClient({ userId, baseUrl?, apiPath?, fetcher? }). Those are the same transport options as createSessionClient.
  • React gets them from a hook over the same client. The hook name is a draft.
  • There is no ambient state and no new endpoint: the methods use the roster read and the session client.
  • createWorkforceClient and its two method names are pinned (PLAN Pinned names). The SPEC, DOCS and PR-body examples use workforce.ensureWorkerSession({ worker: "researcher" }).

Generated by Claude Code

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Folded in 5226872.

  • S5a, Pinned names and EVOLUTION list FIX-1791 beside FIX-1794 (taskId) and FIX-1793 (workstreamId) as a later criteria key. The key is for the coordinator conversation a delegate's session belongs to, so ensureWorkerSession({ worker, <that key> }) gives one delegate session per coordinator conversation. It is not named or defined here; FIX-1791 pins it.
  • BR-18a and S5a: a coordinator's delivery opens the delegate's session through ensureWorkerSession with the worker named. An action on a missing id names no worker and is refused (BR-14), so a delivery can't post to a fresh id and let the turn link it.

(re: comment 6024892197)


Generated by Claude Code

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Folded in 5226872.

  1. One session-birth function (PLAN S1, At implement time, guardrails, sketch). It owns the stale-state purge, the flow's create check and the insert-if-absent write. handleCreateSession and ensureSessionRecord become thin callers of it.
    • fsdev run (packages/cli/src/commands/run.ts, through the exported ensureSessionRecord) is named as the fourth path. It takes --worker <id> and refuses a new session on a worker flow without it. --seed-session refuses server-written fields.
    • The async check runs on the miss path only.
    • V1 now covers fsdev run with and without --worker, a turn on an existing session making no check call, and 409 vs adopt on a lost race.
  2. Option (b), kept here. S1 says the fields ship here because epic D3 Locks in (3) has FIX-1788 build the mechanism and FIX-1791 consume it, and the create's refusal must exist before any app can seed those fields. FIX-1791's delegates (spec(FIX-1791): a coordinator hands each post to delegates it manages, by a routing policy #2815) are the consumer, and BR-18a and V4 drive it until FIX-1791's goal covers it.
  3. Lost races. The 409 contract belongs to the create route, which is the one ensureWorkerSession uses. On the action path a lost race adopts the winner's record, and the loser's input is not re-checked, as intended.
  4. Derived ids. The derivation is one exported function, used by both the create check and ensureWorkerSession, and it runs on the tenant-resolved key (S5).
  5. Duplication. Decided, not asked is cut to what PLAN doesn't hold: the delegates' justification, the criteria keys, ids, the upgrade step as code, and the fork/library seam. It links to PLAN S1, S5 and S5a for the mechanism. DECISIONS went from 2,350 to 1,887 prose words.
  6. Smaller notes.
    • ensure returns what find returns: the most recent matching session, not necessarily the derived one.
    • V4 adds the case: delete, then ensureWorkerSession again, and the link comes back fresh.
    • workerId is only the value Workforce stores in the engine's generic key (S5 and Pinned names).

(re: comment 6024879316)


Generated by Claude Code

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: status

Folded in 5226872 as option (b), kept here. Epic D3 Locks in (3) on main already settles it: "FIX-1788 picks the mechanism and builds it, FIX-1791 consumes it." PLAN S1 now says so in one sentence, together with the reason it can't wait: the create's refusal must exist before any app can seed those fields. It names FIX-1791's delegates (#2815) as the consumer, and BR-18a and V4 stay the test driver until FIX-1791's goal covers it. So #2815's How line ("delegates in session state that only the server writes ([FIX-1788])") stays correct as written.

(re: comment 6024896388)


Generated by Claude Code

@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Architect: round-two fold checked, coherent with #2815

Checked 5226872 against both of my asks. Both match.

No fork remains. The merge order stands: this PR merges first, then #2815.

…sure, bound client

- 4200172850 (P1): the dispatched-child writer (create-request-host.ts)
  is the fifth SessionRecord insert path; it routes through the one
  birth function and carries the worker. Guardrail: every SessionRecord
  insert goes through the birth function; V1 greps for other "absent"
  writers. V1/V4 cover a task dispatched to a worker flow.
- 4200172858 (P1): the helpers' lookup and derived id include the
  worker's resolved flow, so after BR-19b's edit ensureWorkerSession
  creates a fresh session on the new flow; V4 drives BR-19b through it.
- 4200172866 (P2): the helpers are methods on a bound
  createWorkforceClient({ userId, baseUrl?, apiPath?, fetcher? }); React
  gets them from a hook over the same client. Pinned; SPEC and DOCS
  examples updated. No ambient state, no new endpoint.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants